home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 November / EnigmA AMIGA RUN 02 (1995)(G.R. Edizioni)(IT)[!][issue 1995-11][Skylink CD].iso / earcd / program / misc / mkdepend.lha / MkDepend-1.0 / MkDepend.doc < prev    next >
Text File  |  1995-09-19  |  9KB  |  269 lines
  1. $VER: MkDepend:doc 1.0 (18-Sep-95)
  2.  
  3.                                  MkDepend 1.0
  4.  
  5.                        Copyright © 1995 by Lars Düning
  6.                              All Rights Reserved.
  7.                   Permission granted for non-commercial use.
  8.  
  9.  
  10. Introduction
  11. ------------
  12.   Makefiles are very useful in the development of larger program systems,
  13.   as they notate the various dependencies and associated needed actions
  14.   in a machine-useable notation. Unfortunately it's the most important
  15.   dependency between C sources and their includes which have to be
  16.   maintained by hand, a most boring and errorprone task. MkDepend is one
  17.   of those programs which attempt to automate this part of development
  18.   by scanning source files for includes and repeating this step
  19.   recursively until the complete transitive closure of included files
  20.   is determined. The found dependencies are then written into an
  21.   existing makefile, keeping it up to date.
  22.  
  23. Usage
  24. -----
  25.   MkDepend is a CLI-only program, needs at least OS 2.0 and 10 KByte stack.
  26.  
  27.   Template: -F=MAKE/K,-I=INCLUDE/K/M,-X=EXCEPT/K/M,-S=SUFFIX/K/M,
  28.             -P=OBJPAT/K/M,-V=VERBOSE/S,FILES/M
  29.  
  30.   mkdepend  {-i|INCLUDE <includepath>[::<symbol>]}
  31.             {-x|EXCEPT  <filepattern>}
  32.             {-s|SUFFIX  <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  33.             {-p|OBJPAT  <src_ext>{,<src_ext>}:<obj_pattern>
  34.             [-f|MAKE    <makefile>]
  35.             [-v|VERBOSE]
  36.             {<filepattern>}
  37.  
  38.  
  39.     The space between the short form of the keywords and their operands
  40.     may be omitted. For example
  41.  
  42.       mkdepend -IINCLUDE:
  43.       mkdepend -I INCLUDE:
  44.       mkdepend -I=INCLUDE:
  45.  
  46.     are equivalent.
  47.  
  48.  
  49.   MkDepend is given a 'skeleton' of C source files and searches them for
  50.   included files. The Includes found are recursively searched for includes
  51.   themselves, until the complete transitive closure has been determined.
  52.   MkDepend searches the includes first in the current directory, then in
  53.   the given paths (if any), imitating the C preprocessor's behaviour.
  54.   The files are scanned for include statements of the form
  55.  
  56.     #include "<filename>"
  57.  
  58.   excluding those which are commented out using C-style /* */- or
  59.   C++-style //-comments. Every other content of the files is ignored.
  60.  
  61.   After all includes have been found, the dependencies are written into
  62.   a makefile (creating it if necessary). The makefile is searched for
  63.   a line
  64.  
  65.     # --- DO NOT MODIFY THIS LINE -- AUTO-DEPENDS FOLLOW ---
  66.  
  67.   after which MkDepend adds the dependencies, overwriting old ones.
  68.   If the line is not found, it and the dependencies are added to the
  69.   file. Existing Makefiles are modified by renaming it to <origname>.bak
  70.   and then re-creating the Makefile by copying the data not to be
  71.   modified.
  72.  
  73.   The found dependencies for the 'skeleton' files are written as
  74.  
  75.     <skeleton> : <included file 1> <included file 2>...
  76.  
  77.   Lines are limited to 80 chars, longer entries are folded into several
  78.   lines, ending each but the last line with a backslash (\).
  79.  
  80.   MkDepend can be teached to know about source/object file relationships
  81.   to be used in the entries written. E,g, the entry generated for a typical
  82.   C source file would be of the form
  83.  
  84.     <skeleton>.o : <skeleton>.c <include 1> <include 2> ...
  85.  
  86.   Includes appear with that path in the list under which MkDepend found
  87.   them. To support multi-platform development, replacement texts may
  88.   be specified for the paths which are then used instead in the output.
  89.  
  90.  
  91. Arguments
  92. ---------
  93.  
  94.   <filepattern>
  95.  
  96.     Any command argument not recognizable as option is considered as
  97.     specification of one of the 'skeleton' sources.
  98.     Wildcards are recognized.
  99.  
  100.     Default: #?.c
  101.  
  102.     Example:
  103.  
  104.       mkdepend #?.c #?.cc
  105.  
  106.         All files ending in ".c" or ".cc" are considered.
  107.  
  108.    ------
  109.  
  110.   -x     <filepattern>
  111.   EXCEPT <filepattern>
  112.  
  113.     Files which are not part of the 'skeleton', even if they are specified
  114.     as such.
  115.  
  116.     Example:
  117.  
  118.       mkdepend #?.c -x test#?
  119.  
  120.         All files ending in ".c", except those whose name start with "test",
  121.         are considered as sources.
  122.  
  123.    ------
  124.  
  125.   -i      <includepath>[::<symbol>]}
  126.   INCLUDE <includepath>[::<symbol>]}
  127.  
  128.      Specify a directory to be searched for include files. The paths are
  129.      searched in the order given on the command line. The current
  130.      directory is always searched first.
  131.  
  132.      If <symbol> is specified, the <includepath> is replaced by it in
  133.      the dependencies written to the makefile.
  134.  
  135.      Example:
  136.  
  137.        mkdepend -i INCLUDE:
  138.  
  139.          Include files are searched in the current directory and in INCLUDE: .
  140.  
  141.        mkdepend -I INCLUDE:pdlibs::$(PDLIBS)
  142.  
  143.          Include files are searched in the current directory and
  144.          in INCLUDE:pdlibs. A file like "INCLUDE:pdlibs/tree.h" will be
  145.          written as "$(PDLIBS)tree.h" into the makefile.
  146.  
  147.    ------
  148.  
  149.   -s     <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  150.   SUFFIX <src_ext>{,<src_ext>}[:<obj_ext>] | :<obj_ext>}
  151.  
  152.     Specify a name relationship between source and object files.
  153.     If a source name ends in one of the given <src_ext>s, an Makefile entry
  154.     with the object name constructed using the associated <obj_ext>.
  155.     The <obj_ext> given with no associated <src_ext> serves as default
  156.     extension used for those <src_ext> which are given without own
  157.     <obj_ext>.
  158.  
  159.     Default: -s :.o -s .c
  160.  
  161.     Example:
  162.  
  163.       mkdepend -s :.o -s .c,.cc
  164.  
  165.         Default <obj_ext> is ".obj", which is used for files with the
  166.         extension ".c" and ".cc".
  167.  
  168.    ------
  169.  
  170.   -p      <src_ext>{,<src_ext>}:<obj_pattern>
  171.   OBJPAT  <src_ext>{,<src_ext>}:<obj_pattern>
  172.  
  173.     Similar to SUFFIX, but allows more complicated name relations.
  174.     <obj_pattern> gives the object file name verbatim, using placeholders
  175.     for the actual filenames:
  176.  
  177.       %s: the full sourcename (w/o suffix)
  178.       %p: the path part of the sourcename
  179.       %n: the base of the sourcename (w/o suffix)
  180.       %x: the character x for every x != s, p or n.
  181.  
  182.     Example:
  183.  
  184.       mkdepend -p .c:obj/%n.o
  185.  
  186.         For every sourcefile <name>.c, an entry for obj/<name>.o is
  187.         created.
  188.  
  189.    ------
  190.  
  191.   -f    <makefile>
  192.   MAKE  <makefile>
  193.  
  194.     Specify the makefile to modify. If not specified, MkDepend searches
  195.     in order for "Makefile", "Makefile.mk", "DMakefile" and "SMakefile".
  196.     If none of these exists, "Makefile" is used.
  197.  
  198.    ------
  199.  
  200.   -v
  201.   VERBOSE
  202.  
  203.     Print some output during operation, namely the program name and the
  204.     file currently under examination.
  205.  
  206.  
  207. Installation
  208. ------------
  209.   Copy the executable "MkDepend" into a suiting directory, profitably
  210.   into one in your search path. That's it.
  211.  
  212.  
  213. Program Information
  214. -------------------
  215.   MkDepend consists of three source files with associated includes:
  216.  
  217.     reader.c,.h: Reading of source files and scanning for #include statements.
  218.                  Copying and writing of makefiles.
  219.     nodes.c,.h : Management of the names and locations of the files analysed.
  220.                  It is implemented as a binary search tree with an addition
  221.                  linked list.
  222.     main.c     : Commandline parsing and program control.
  223.  
  224.   To recreate MkDepend, compile the three sources and link them.
  225.  
  226.   MkDepend was written for DICE 3.01, makefiles are provided for use with
  227.   DICE own dmake (`DMakefile') and Dennis Vadura's DMake (`Makefile').
  228.  
  229.  
  230. Bugs/TODO
  231. ---------
  232.   main.c is a nasty mixture of Amiga specific and generic code.
  233.   Wildcard expansion is done using DICE' expand_files(), which does not
  234.     accept the full set of wildcards implemented by AmigaDOS.
  235.  
  236.  
  237. Author
  238. ------
  239.   Lars Düning, Am Wendenwehr 25, 38114 Braunschweig, Germany
  240.   duening@ibr.cs.tu-bs.de
  241.  
  242.   The file reader was inspired by the input module of lcc by David Hanson
  243.   and Christopher Fraser.
  244.  
  245.  
  246. Legalese
  247. --------
  248.   MkDepend is Copyright © 1995 by Lars Düning. All Rights are reserved.
  249.   Permission granted for non-commercial use.
  250.  
  251.   MkDepend may be freely distributed, provided that all copyright notices
  252.   and associated disclaimers are reproduced, and that only a reasonable
  253.   copying fee is charged. MkDepend may be included as "one program among
  254.   many" in (even commercial) software distributions.
  255.   No fee may be charged for MkDepend itself.
  256.  
  257.   MkDepend may be freely modified, provided that the modifications are
  258.   made available to the public, that each changed file carries a notice
  259.   stating who changed what and when, and that the modified versions are
  260.   clearly distinguishable from the original.
  261.  
  262.   Parts of MkDepend may be used in own (even commercial) programs provided
  263.   that proper credit is given.
  264.  
  265.   MkDepend PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
  266.   IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
  267.   WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
  268.  
  269.